<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html 
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Module: ActionView::Helpers::FormHelper</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  <meta http-equiv="Content-Script-Type" content="text/javascript" />
  <link rel="stylesheet" href="../../.././rdoc-style.css" type="text/css" media="screen" />
  <script type="text/javascript">
  // <![CDATA[

  function popupCode( url ) {
    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
  }

  function toggleCode( id ) {
    if ( document.getElementById )
      elem = document.getElementById( id );
    else if ( document.all )
      elem = eval( "document.all." + id );
    else
      return false;

    elemStyle = elem.style;
    
    if ( elemStyle.display != "block" ) {
      elemStyle.display = "block"
    } else {
      elemStyle.display = "none"
    }

    return true;
  }
  
  // Make codeblocks hidden by default
  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
  
  // ]]>
  </script>

</head>
<body>



    <div id="classHeader">
        <table class="header-table">
        <tr class="top-aligned-row">
          <td><strong>Module</strong></td>
          <td class="class-name-in-header">ActionView::Helpers::FormHelper</td>
        </tr>
        <tr class="top-aligned-row">
            <td><strong>In:</strong></td>
            <td>
                <a href="../../../files/vendor/rails/actionpack/lib/action_view/helpers/form_helper_rb.html">
                vendor/rails/actionpack/lib/action_view/helpers/form_helper.rb
                </a>
        <br />
            </td>
        </tr>

        </table>
    </div>
  <!-- banner header -->

  <div id="bodyContent">



  <div id="contextContent">

    <div id="description">
      <p>
Form helpers are designed to make working with models much easier compared
to using just standard HTML elements by providing a set of methods for
creating forms based on your models. This helper generates the HTML for
forms, providing a method for each sort of input (e.g., text, password,
select, and so on). When the form is submitted (i.e., when the user hits
the submit button or <tt>form.submit</tt> is called via JavaScript), the
form inputs will be bundled into the <tt>params</tt> object and passed back
to the controller.
</p>
<p>
There are two types of form helpers: those that specifically work with
model attributes and those that don&#8216;t. This helper deals with those
that work with model attributes; to see an example of form helpers that
don&#8216;t work with model attributes, check the <a
href="FormTagHelper.html">ActionView::Helpers::FormTagHelper</a>
documentation.
</p>
<p>
The core method of this helper, <a
href="FormHelper.html#M000920">form_for</a>, gives you the ability to
create a form for a model instance; for example, let&#8216;s say that you
have a model <tt>Person</tt> and want to create a new instance of it:
</p>
<pre>
    # Note: a @person variable will have been created in the controller.
    # For example: @person = Person.new
    &lt;% form_for :person, @person, :url =&gt; { :action =&gt; &quot;create&quot; } do |f| %&gt;
      &lt;%= f.text_field :first_name %&gt;
      &lt;%= f.text_field :last_name %&gt;
      &lt;%= submit_tag 'Create' %&gt;
    &lt;% end %&gt;
</pre>
<p>
The HTML generated for this would be:
</p>
<pre>
    &lt;form action=&quot;/persons/create&quot; method=&quot;post&quot;&gt;
      &lt;input id=&quot;person_first_name&quot; name=&quot;person[first_name]&quot; size=&quot;30&quot; type=&quot;text&quot; /&gt;
      &lt;input id=&quot;person_last_name&quot; name=&quot;person[last_name]&quot; size=&quot;30&quot; type=&quot;text&quot; /&gt;
      &lt;input name=&quot;commit&quot; type=&quot;submit&quot; value=&quot;Create&quot; /&gt;
    &lt;/form&gt;
</pre>
<p>
The <tt>params</tt> object created when this form is submitted would look
like:
</p>
<pre>
    {&quot;action&quot;=&gt;&quot;create&quot;, &quot;controller&quot;=&gt;&quot;persons&quot;, &quot;person&quot;=&gt;{&quot;first_name&quot;=&gt;&quot;William&quot;, &quot;last_name&quot;=&gt;&quot;Smith&quot;}}
</pre>
<p>
The params hash has a nested <tt>person</tt> value, which can therefore be
accessed with <tt>params[:person]</tt> in the controller. If were
editing/updating an instance (e.g., <tt>Person.find(1)</tt> rather than
<tt>Person.new</tt> in the controller), the objects attribute values are
filled into the form (e.g., the <tt>person_first_name</tt> field would have
that person&#8216;s first name in it).
</p>
<p>
If the object name contains square brackets the id for the object will be
inserted. For example:
</p>
<pre>
  &lt;%= text_field &quot;person[]&quot;, &quot;name&quot; %&gt;
</pre>
<p>
&#8230;will generate the following ERb.
</p>
<pre>
  &lt;input type=&quot;text&quot; id=&quot;person_&lt;%= @person.id %&gt;_name&quot; name=&quot;person[&lt;%= @person.id %&gt;][name]&quot; value=&quot;&lt;%= @person.name %&gt;&quot; /&gt;
</pre>
<p>
If the helper is being used to generate a repetitive sequence of similar
form elements, for example in a partial used by
<tt>render_collection_of_partials</tt>, the <tt>index</tt> option may come
in handy. Example:
</p>
<pre>
  &lt;%= text_field &quot;person&quot;, &quot;name&quot;, &quot;index&quot; =&gt; 1 %&gt;
</pre>
<p>
&#8230;becomes&#8230;
</p>
<pre>
  &lt;input type=&quot;text&quot; id=&quot;person_1_name&quot; name=&quot;person[1][name]&quot; value=&quot;&lt;%= @person.name %&gt;&quot; /&gt;
</pre>
<p>
There are also methods for helping to build form tags in <a
href="FormOptionsHelper.html">classes/ActionView/Helpers/FormOptionsHelper.html</a>,
<a href="DateHelper.html">classes/ActionView/Helpers/DateHelper.html</a>,
and <a
href="ActiveRecordHelper.html">classes/ActionView/Helpers/ActiveRecordHelper.html</a>
</p>

    </div>


   </div>

    <div id="method-list">
      <h3 class="section-bar">Methods</h3>

      <div class="name-list">
      <a href="#M000928">check_box</a>&nbsp;&nbsp;
      <a href="#M000921">fields_for</a>&nbsp;&nbsp;
      <a href="#M000926">file_field</a>&nbsp;&nbsp;
      <a href="#M000920">form_for</a>&nbsp;&nbsp;
      <a href="#M000925">hidden_field</a>&nbsp;&nbsp;
      <a href="#M000922">label</a>&nbsp;&nbsp;
      <a href="#M000924">password_field</a>&nbsp;&nbsp;
      <a href="#M000929">radio_button</a>&nbsp;&nbsp;
      <a href="#M000927">text_area</a>&nbsp;&nbsp;
      <a href="#M000923">text_field</a>&nbsp;&nbsp;
      </div>
    </div>

  </div>


    <!-- if includes -->

    <div id="section">





      


    <!-- if method_list -->
    <div id="methods">
      <h3 class="section-bar">Public Instance methods</h3>

      <div id="method-M000928" class="method-detail">
        <a name="M000928"></a>

        <div class="method-heading">
          <a href="#M000928" class="method-signature">
          <span class="method-name">check_box</span><span class="method-args">(object_name, method, options = {}, checked_value = &quot;1&quot;, unchecked_value = &quot;0&quot;)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Returns a checkbox tag tailored for accessing a specified attribute
(identified by <tt>method</tt>) on an object assigned to the template
(identified by <tt>object</tt>). It&#8216;s intended that <tt>method</tt>
returns an integer and if that integer is above zero, then the checkbox is
checked. Additional options on the input tag can be passed as a hash with
<tt>options</tt>. The <tt>checked_value</tt> defaults to 1 while the
default <tt>unchecked_value</tt> is set to 0 which is convenient for
boolean values. Since HTTP standards say that unchecked checkboxes
don&#8216;t post anything, we add a hidden value with the same name as the
checkbox as a work around.
</p>
<h4>Examples</h4>
<pre>
  # Let's say that @post.validated? is 1:
  check_box(&quot;post&quot;, &quot;validated&quot;)
  # =&gt; &lt;input type=&quot;checkbox&quot; id=&quot;post_validate&quot; name=&quot;post[validated]&quot; value=&quot;1&quot; checked=&quot;checked&quot; /&gt;
  #    &lt;input name=&quot;post[validated]&quot; type=&quot;hidden&quot; value=&quot;0&quot; /&gt;

  # Let's say that @puppy.gooddog is &quot;no&quot;:
  check_box(&quot;puppy&quot;, &quot;gooddog&quot;, {}, &quot;yes&quot;, &quot;no&quot;)
  # =&gt; &lt;input type=&quot;checkbox&quot; id=&quot;puppy_gooddog&quot; name=&quot;puppy[gooddog]&quot; value=&quot;yes&quot; /&gt;
  #    &lt;input name=&quot;puppy[gooddog]&quot; type=&quot;hidden&quot; value=&quot;no&quot; /&gt;

  check_box(&quot;eula&quot;, &quot;accepted&quot;, {}, &quot;yes&quot;, &quot;no&quot;, :class =&gt; 'eula_check')
  # =&gt; &lt;input type=&quot;checkbox&quot; id=&quot;eula_accepted&quot; name=&quot;eula[accepted]&quot; value=&quot;no&quot; /&gt;
  #    &lt;input name=&quot;eula[accepted]&quot; type=&quot;hidden&quot; value=&quot;no&quot; /&gt;
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000928-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000928-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_view/helpers/form_helper.rb, line 401</span>
401:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">check_box</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-identifier">options</span> = {}, <span class="ruby-identifier">checked_value</span> = <span class="ruby-value str">&quot;1&quot;</span>, <span class="ruby-identifier">unchecked_value</span> = <span class="ruby-value str">&quot;0&quot;</span>)
402:         <span class="ruby-constant">InstanceTag</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-keyword kw">self</span>, <span class="ruby-keyword kw">nil</span>, <span class="ruby-identifier">options</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">:object</span>)).<span class="ruby-identifier">to_check_box_tag</span>(<span class="ruby-identifier">options</span>, <span class="ruby-identifier">checked_value</span>, <span class="ruby-identifier">unchecked_value</span>)
403:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000921" class="method-detail">
        <a name="M000921"></a>

        <div class="method-heading">
          <a href="#M000921" class="method-signature">
          <span class="method-name">fields_for</span><span class="method-args">(record_or_name_or_array, *args) {|builder.new(object_name, object, self, options, block)| ...}</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Creates a scope around a specific model object like <a
href="FormHelper.html#M000920">form_for</a>, but doesn&#8216;t create the
form tags themselves. This makes <a
href="FormHelper.html#M000921">fields_for</a> suitable for specifying
additional model objects in the same form:
</p>
<h4>Examples</h4>
<pre>
  &lt;% form_for @person, :url =&gt; { :action =&gt; &quot;update&quot; } do |person_form| %&gt;
    First name: &lt;%= person_form.text_field :first_name %&gt;
    Last name : &lt;%= person_form.text_field :last_name %&gt;

    &lt;% fields_for @person.permission do |permission_fields| %&gt;
      Admin?  : &lt;%= permission_fields.check_box :admin %&gt;
    &lt;% end %&gt;
  &lt;% end %&gt;
</pre>
<p>
&#8230;or if you have an object that needs to be represented as a different
parameter, like a Client that acts as a Person:
</p>
<pre>
  &lt;% fields_for :person, @client do |permission_fields| %&gt;
    Admin?: &lt;%= permission_fields.check_box :admin %&gt;
  &lt;% end %&gt;
</pre>
<p>
&#8230;or if you don&#8216;t have an object, just a name of the parameter
</p>
<pre>
  &lt;% fields_for :person do |permission_fields| %&gt;
    Admin?: &lt;%= permission_fields.check_box :admin %&gt;
  &lt;% end %&gt;
</pre>
<p>
Note: This also works for the methods in FormOptionHelper and <a
href="DateHelper.html">DateHelper</a> that are designed to work with an
object as base, like FormOptionHelper#collection_select and <a
href="DateHelper.html#M001011">DateHelper#datetime_select</a>.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000921-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000921-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_view/helpers/form_helper.rb, line 230</span>
230:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">fields_for</span>(<span class="ruby-identifier">record_or_name_or_array</span>, <span class="ruby-operator">*</span><span class="ruby-identifier">args</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span>)
231:         <span class="ruby-identifier">raise</span> <span class="ruby-constant">ArgumentError</span>, <span class="ruby-value str">&quot;Missing block&quot;</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">block_given?</span>
232:         <span class="ruby-identifier">options</span> = <span class="ruby-identifier">args</span>.<span class="ruby-identifier">extract_options!</span>
233: 
234:         <span class="ruby-keyword kw">case</span> <span class="ruby-identifier">record_or_name_or_array</span>
235:         <span class="ruby-keyword kw">when</span> <span class="ruby-constant">String</span>, <span class="ruby-constant">Symbol</span>
236:           <span class="ruby-identifier">object_name</span> = <span class="ruby-identifier">record_or_name_or_array</span>
237:           <span class="ruby-identifier">object</span> = <span class="ruby-identifier">args</span>.<span class="ruby-identifier">first</span>
238:         <span class="ruby-keyword kw">when</span> <span class="ruby-constant">Array</span>
239:           <span class="ruby-identifier">object</span> = <span class="ruby-identifier">record_or_name_or_array</span>.<span class="ruby-identifier">last</span>
240:           <span class="ruby-identifier">object_name</span> = <span class="ruby-constant">ActionController</span><span class="ruby-operator">::</span><span class="ruby-constant">RecordIdentifier</span>.<span class="ruby-identifier">singular_class_name</span>(<span class="ruby-identifier">object</span>)
241:           <span class="ruby-identifier">apply_form_for_options!</span>(<span class="ruby-identifier">record_or_name_or_array</span>, <span class="ruby-identifier">options</span>)
242:         <span class="ruby-keyword kw">else</span>
243:           <span class="ruby-identifier">object</span> = <span class="ruby-identifier">record_or_name_or_array</span>
244:           <span class="ruby-identifier">object_name</span> = <span class="ruby-constant">ActionController</span><span class="ruby-operator">::</span><span class="ruby-constant">RecordIdentifier</span>.<span class="ruby-identifier">singular_class_name</span>(<span class="ruby-identifier">object</span>)
245:         <span class="ruby-keyword kw">end</span>
246: 
247:         <span class="ruby-identifier">builder</span> = <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:builder</span>] <span class="ruby-operator">||</span> <span class="ruby-constant">ActionView</span><span class="ruby-operator">::</span><span class="ruby-constant">Base</span>.<span class="ruby-identifier">default_form_builder</span>
248:         <span class="ruby-keyword kw">yield</span> <span class="ruby-identifier">builder</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">object</span>, <span class="ruby-keyword kw">self</span>, <span class="ruby-identifier">options</span>, <span class="ruby-identifier">block</span>)
249:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000926" class="method-detail">
        <a name="M000926"></a>

        <div class="method-heading">
          <a href="#M000926" class="method-signature">
          <span class="method-name">file_field</span><span class="method-args">(object_name, method, options = {})</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Returns an file upload input tag tailored for accessing a specified
attribute (identified by <tt>method</tt>) on an object assigned to the
template (identified by <tt>object</tt>). Additional options on the input
tag can be passed as a hash with <tt>options</tt>. These options will be
tagged onto the HTML as an HTML element attribute as in the example shown.
</p>
<h4>Examples</h4>
<pre>
  file_field(:user, :avatar)
  # =&gt; &lt;input type=&quot;file&quot; id=&quot;user_avatar&quot; name=&quot;user[avatar]&quot; /&gt;

  file_field(:post, :attached, :accept =&gt; 'text/html')
  # =&gt; &lt;input type=&quot;file&quot; id=&quot;post_attached&quot; name=&quot;post[attached]&quot; /&gt;

  file_field(:attachment, :file, :class =&gt; 'file_input')
  # =&gt; &lt;input type=&quot;file&quot; id=&quot;attachment_file&quot; name=&quot;attachment[file]&quot; class=&quot;file_input&quot; /&gt;
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000926-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000926-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_view/helpers/form_helper.rb, line 347</span>
347:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">file_field</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-identifier">options</span> = {})
348:         <span class="ruby-constant">InstanceTag</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-keyword kw">self</span>, <span class="ruby-keyword kw">nil</span>, <span class="ruby-identifier">options</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">:object</span>)).<span class="ruby-identifier">to_input_field_tag</span>(<span class="ruby-value str">&quot;file&quot;</span>, <span class="ruby-identifier">options</span>)
349:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000920" class="method-detail">
        <a name="M000920"></a>

        <div class="method-heading">
          <a href="#M000920" class="method-signature">
          <span class="method-name">form_for</span><span class="method-args">(record_or_name_or_array, *args, &amp;proc)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Creates a form and a scope around a specific model object that is used as a
base for questioning about values for the fields.
</p>
<pre>
  &lt;% form_for :person, @person, :url =&gt; { :action =&gt; &quot;update&quot; } do |f| %&gt;
    First name: &lt;%= f.text_field :first_name %&gt;
    Last name : &lt;%= f.text_field :last_name %&gt;
    Biography : &lt;%= f.text_area :biography %&gt;
    Admin?    : &lt;%= f.check_box :admin %&gt;
  &lt;% end %&gt;
</pre>
<p>
Worth noting is that the <a href="FormHelper.html#M000920">form_for</a> tag
is called in a ERb evaluation block, not an ERb output block. So
that&#8216;s <tt>&lt;% %&gt;</tt>, not <tt>&lt;%= %&gt;</tt>. Also worth
noting is that <a href="FormHelper.html#M000920">form_for</a> yields a
<tt>form_builder</tt> object, in this example as <tt>f</tt>, which emulates
the API for the stand-alone <a href="FormHelper.html">FormHelper</a>
methods, but without the object name. So instead of <tt><a
href="FormHelper.html#M000923">text_field</a> :person, :name</tt>, you get
away with <tt>f.text_field :name</tt>.
</p>
<p>
Even further, the <a href="FormHelper.html#M000920">form_for</a> method
allows you to more easily escape the instance variable convention. So while
the stand-alone approach would require <tt><a
href="FormHelper.html#M000923">text_field</a> :person, :name, :object =&gt;
person</tt> to work with local variables instead of instance ones, the <a
href="FormHelper.html#M000920">form_for</a> calls remain the same. You
simply declare once with <tt>:person, person</tt> and all subsequent field
calls save <tt>:person</tt> and <tt>:object =&gt; person</tt>.
</p>
<p>
Also note that <a href="FormHelper.html#M000920">form_for</a> doesn&#8216;t
create an exclusive scope. It&#8216;s still possible to use both the
stand-alone <a href="FormHelper.html">FormHelper</a> methods and methods
from <a href="FormTagHelper.html">FormTagHelper</a>. For example:
</p>
<pre>
  &lt;% form_for :person, @person, :url =&gt; { :action =&gt; &quot;update&quot; } do |f| %&gt;
    First name: &lt;%= f.text_field :first_name %&gt;
    Last name : &lt;%= f.text_field :last_name %&gt;
    Biography : &lt;%= text_area :person, :biography %&gt;
    Admin?    : &lt;%= check_box_tag &quot;person[admin]&quot;, @person.company.admin? %&gt;
  &lt;% end %&gt;
</pre>
<p>
Note: This also works for the methods in FormOptionHelper and <a
href="DateHelper.html">DateHelper</a> that are designed to work with an
object as base, like FormOptionHelper#collection_select and <a
href="DateHelper.html#M001011">DateHelper#datetime_select</a>.
</p>
<p>
HTML attributes for the form tag can be given as :html =&gt; {&#8230;}. For
example:
</p>
<pre>
  &lt;% form_for :person, @person, :html =&gt; {:id =&gt; 'person_form'} do |f| %&gt;
    ...
  &lt;% end %&gt;
</pre>
<p>
The above form will then have the <tt>id</tt> attribute with the value
&lt;/tt&gt;person_form&lt;/tt&gt;, which you can then style with CSS or
manipulate with JavaScript.
</p>
<h3>Relying on record identification</h3>
<p>
In addition to manually configuring the <a
href="FormHelper.html#M000920">form_for</a> call, you can also rely on
record identification, which will use the conventions and named routes of
that approach. Examples:
</p>
<pre>
  &lt;% form_for(@post) do |f| %&gt;
    ...
  &lt;% end %&gt;
</pre>
<p>
This will expand to be the same as:
</p>
<pre>
  &lt;% form_for :post, @post, :url =&gt; post_path(@post), :html =&gt; { :method =&gt; :put, :class =&gt; &quot;edit_post&quot;, :id =&gt; &quot;edit_post_45&quot; } do |f| %&gt;
    ...
  &lt;% end %&gt;
</pre>
<p>
And for new records:
</p>
<pre>
  &lt;% form_for(Post.new) do |f| %&gt;
    ...
  &lt;% end %&gt;
</pre>
<p>
This will expand to be the same as:
</p>
<pre>
  &lt;% form_for :post, @post, :url =&gt; posts_path, :html =&gt; { :class =&gt; &quot;new_post&quot;, :id =&gt; &quot;new_post&quot; } do |f| %&gt;
    ...
  &lt;% end %&gt;
</pre>
<p>
You can also overwrite the individual conventions, like this:
</p>
<pre>
  &lt;% form_for(@post, :url =&gt; super_post_path(@post)) do |f| %&gt;
    ...
  &lt;% end %&gt;
</pre>
<p>
And for namespaced routes, like admin_post_url:
</p>
<pre>
  &lt;% form_for([:admin, @post]) do |f| %&gt;
   ...
  &lt;% end %&gt;
</pre>
<h3>Customized form builders</h3>
<p>
You can also build forms using a customized FormBuilder class. Subclass
FormBuilder and override or define some more helpers, then use your custom
builder. For example, let&#8216;s say you made a helper to automatically
add labels to form inputs.
</p>
<pre>
  &lt;% form_for :person, @person, :url =&gt; { :action =&gt; &quot;update&quot; }, :builder =&gt; LabellingFormBuilder do |f| %&gt;
    &lt;%= f.text_field :first_name %&gt;
    &lt;%= f.text_field :last_name %&gt;
    &lt;%= text_area :person, :biography %&gt;
    &lt;%= check_box_tag &quot;person[admin]&quot;, @person.company.admin? %&gt;
  &lt;% end %&gt;
</pre>
<p>
In many cases you will want to wrap the above in another helper, so you
could do something like the following:
</p>
<pre>
  def labelled_form_for(name, object, options, &amp;proc)
    form_for(name, object, options.merge(:builder =&gt; LabellingFormBuiler), &amp;proc)
  end
</pre>
<p>
If you don&#8216;t need to attach a form to a model instance, then check
out <a href="FormTagHelper.html#M001036">FormTagHelper#form_tag</a>.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000920-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000920-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_view/helpers/form_helper.rb, line 163</span>
163:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">form_for</span>(<span class="ruby-identifier">record_or_name_or_array</span>, <span class="ruby-operator">*</span><span class="ruby-identifier">args</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">proc</span>)
164:         <span class="ruby-identifier">raise</span> <span class="ruby-constant">ArgumentError</span>, <span class="ruby-value str">&quot;Missing block&quot;</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">block_given?</span>
165: 
166:         <span class="ruby-identifier">options</span> = <span class="ruby-identifier">args</span>.<span class="ruby-identifier">extract_options!</span>
167: 
168:         <span class="ruby-keyword kw">case</span> <span class="ruby-identifier">record_or_name_or_array</span>
169:         <span class="ruby-keyword kw">when</span> <span class="ruby-constant">String</span>, <span class="ruby-constant">Symbol</span>
170:           <span class="ruby-identifier">object_name</span> = <span class="ruby-identifier">record_or_name_or_array</span>
171:         <span class="ruby-keyword kw">when</span> <span class="ruby-constant">Array</span>
172:           <span class="ruby-identifier">object</span> = <span class="ruby-identifier">record_or_name_or_array</span>.<span class="ruby-identifier">last</span>
173:           <span class="ruby-identifier">object_name</span> = <span class="ruby-constant">ActionController</span><span class="ruby-operator">::</span><span class="ruby-constant">RecordIdentifier</span>.<span class="ruby-identifier">singular_class_name</span>(<span class="ruby-identifier">object</span>)
174:           <span class="ruby-identifier">apply_form_for_options!</span>(<span class="ruby-identifier">record_or_name_or_array</span>, <span class="ruby-identifier">options</span>)
175:           <span class="ruby-identifier">args</span>.<span class="ruby-identifier">unshift</span> <span class="ruby-identifier">object</span>
176:         <span class="ruby-keyword kw">else</span>
177:           <span class="ruby-identifier">object</span> = <span class="ruby-identifier">record_or_name_or_array</span>
178:           <span class="ruby-identifier">object_name</span> = <span class="ruby-constant">ActionController</span><span class="ruby-operator">::</span><span class="ruby-constant">RecordIdentifier</span>.<span class="ruby-identifier">singular_class_name</span>(<span class="ruby-identifier">object</span>)
179:           <span class="ruby-identifier">apply_form_for_options!</span>([<span class="ruby-identifier">object</span>], <span class="ruby-identifier">options</span>)
180:           <span class="ruby-identifier">args</span>.<span class="ruby-identifier">unshift</span> <span class="ruby-identifier">object</span>
181:         <span class="ruby-keyword kw">end</span>
182: 
183:         <span class="ruby-identifier">concat</span>(<span class="ruby-identifier">form_tag</span>(<span class="ruby-identifier">options</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">:url</span>) <span class="ruby-operator">||</span> {}, <span class="ruby-identifier">options</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">:html</span>) <span class="ruby-operator">||</span> {}), <span class="ruby-identifier">proc</span>.<span class="ruby-identifier">binding</span>)
184:         <span class="ruby-identifier">fields_for</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-operator">*</span>(<span class="ruby-identifier">args</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-identifier">options</span>), <span class="ruby-operator">&amp;</span><span class="ruby-identifier">proc</span>)
185:         <span class="ruby-identifier">concat</span>(<span class="ruby-value str">'&lt;/form&gt;'</span>, <span class="ruby-identifier">proc</span>.<span class="ruby-identifier">binding</span>)
186:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000925" class="method-detail">
        <a name="M000925"></a>

        <div class="method-heading">
          <a href="#M000925" class="method-signature">
          <span class="method-name">hidden_field</span><span class="method-args">(object_name, method, options = {})</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Returns a hidden input tag tailored for accessing a specified attribute
(identified by <tt>method</tt>) on an object assigned to the template
(identified by <tt>object</tt>). Additional options on the input tag can be
passed as a hash with <tt>options</tt>. These options will be tagged onto
the HTML as an HTML element attribute as in the example shown.
</p>
<h4>Examples</h4>
<pre>
  hidden_field(:signup, :pass_confirm)
  # =&gt; &lt;input type=&quot;hidden&quot; id=&quot;signup_pass_confirm&quot; name=&quot;signup[pass_confirm]&quot; value=&quot;#{@signup.pass_confirm}&quot; /&gt;

  hidden_field(:post, :tag_list)
  # =&gt; &lt;input type=&quot;hidden&quot; id=&quot;post_tag_list&quot; name=&quot;post[tag_list]&quot; value=&quot;#{@post.tag_list}&quot; /&gt;

  hidden_field(:user, :token)
  # =&gt; &lt;input type=&quot;hidden&quot; id=&quot;user_token&quot; name=&quot;user[token]&quot; value=&quot;#{@user.token}&quot; /&gt;
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000925-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000925-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_view/helpers/form_helper.rb, line 328</span>
328:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">hidden_field</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-identifier">options</span> = {})
329:         <span class="ruby-constant">InstanceTag</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-keyword kw">self</span>, <span class="ruby-keyword kw">nil</span>, <span class="ruby-identifier">options</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">:object</span>)).<span class="ruby-identifier">to_input_field_tag</span>(<span class="ruby-value str">&quot;hidden&quot;</span>, <span class="ruby-identifier">options</span>)
330:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000922" class="method-detail">
        <a name="M000922"></a>

        <div class="method-heading">
          <a href="#M000922" class="method-signature">
          <span class="method-name">label</span><span class="method-args">(object_name, method, text = nil, options = {})</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Returns a <a href="FormHelper.html#M000922">label</a> tag tailored for
labelling an input field for a specified attribute (identified by
<tt>method</tt>) on an object assigned to the template (identified by
<tt>object</tt>). The text of <a href="FormHelper.html#M000922">label</a>
will default to the attribute name unless you specify it explicitly.
Additional options on the <a href="FormHelper.html#M000922">label</a> tag
can be passed as a hash with <tt>options</tt>. These options will be tagged
onto the HTML as an HTML element attribute as in the example shown.
</p>
<h4>Examples</h4>
<pre>
  label(:post, :title)
  #=&gt; &lt;label for=&quot;post_title&quot;&gt;Title&lt;/label&gt;

  label(:post, :title, &quot;A short title&quot;)
  #=&gt; &lt;label for=&quot;post_title&quot;&gt;A short title&lt;/label&gt;

  label(:post, :title, &quot;A short title&quot;, :class =&gt; &quot;title_label&quot;)
  #=&gt; &lt;label for=&quot;post_title&quot; class=&quot;title_label&quot;&gt;A short title&lt;/label&gt;
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000922-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000922-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_view/helpers/form_helper.rb, line 266</span>
266:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">label</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-identifier">text</span> = <span class="ruby-keyword kw">nil</span>, <span class="ruby-identifier">options</span> = {})
267:         <span class="ruby-constant">InstanceTag</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-keyword kw">self</span>, <span class="ruby-keyword kw">nil</span>, <span class="ruby-identifier">options</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">:object</span>)).<span class="ruby-identifier">to_label_tag</span>(<span class="ruby-identifier">text</span>, <span class="ruby-identifier">options</span>)
268:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000924" class="method-detail">
        <a name="M000924"></a>

        <div class="method-heading">
          <a href="#M000924" class="method-signature">
          <span class="method-name">password_field</span><span class="method-args">(object_name, method, options = {})</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Returns an input tag of the &quot;password&quot; type tailored for
accessing a specified attribute (identified by <tt>method</tt>) on an
object assigned to the template (identified by <tt>object</tt>). Additional
options on the input tag can be passed as a hash with <tt>options</tt>.
These options will be tagged onto the HTML as an HTML element attribute as
in the example shown.
</p>
<h4>Examples</h4>
<pre>
  password_field(:login, :pass, :size =&gt; 20)
  # =&gt; &lt;input type=&quot;text&quot; id=&quot;login_pass&quot; name=&quot;login[pass]&quot; size=&quot;20&quot; value=&quot;#{@login.pass}&quot; /&gt;

  password_field(:account, :secret, :class =&gt; &quot;form_input&quot;)
  # =&gt; &lt;input type=&quot;text&quot; id=&quot;account_secret&quot; name=&quot;account[secret]&quot; value=&quot;#{@account.secret}&quot; class=&quot;form_input&quot; /&gt;

  password_field(:user, :password, :onchange =&gt; &quot;if $('user[password]').length &gt; 30 { alert('Your password needs to be shorter!'); }&quot;)
  # =&gt; &lt;input type=&quot;text&quot; id=&quot;user_password&quot; name=&quot;user[password]&quot; value=&quot;#{@user.password}&quot; onchange = &quot;if $('user[password]').length &gt; 30 { alert('Your password needs to be shorter!'); }&quot;/&gt;

  password_field(:account, :pin, :size =&gt; 20, :class =&gt; 'form_input')
  # =&gt; &lt;input type=&quot;text&quot; id=&quot;account_pin&quot; name=&quot;account[pin]&quot; size=&quot;20&quot; value=&quot;#{@account.pin}&quot; class=&quot;form_input&quot; /&gt;
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000924-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000924-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_view/helpers/form_helper.rb, line 310</span>
310:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">password_field</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-identifier">options</span> = {})
311:         <span class="ruby-constant">InstanceTag</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-keyword kw">self</span>, <span class="ruby-keyword kw">nil</span>, <span class="ruby-identifier">options</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">:object</span>)).<span class="ruby-identifier">to_input_field_tag</span>(<span class="ruby-value str">&quot;password&quot;</span>, <span class="ruby-identifier">options</span>)
312:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000929" class="method-detail">
        <a name="M000929"></a>

        <div class="method-heading">
          <a href="#M000929" class="method-signature">
          <span class="method-name">radio_button</span><span class="method-args">(object_name, method, tag_value, options = {})</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Returns a radio button tag for accessing a specified attribute (identified
by <tt>method</tt>) on an object assigned to the template (identified by
<tt>object</tt>). If the current value of <tt>method</tt> is
<tt>tag_value</tt> the radio button will be checked. Additional options on
the input tag can be passed as a hash with <tt>options</tt>.
</p>
<h4>Examples</h4>
<pre>
  # Let's say that @post.category returns &quot;rails&quot;:
  radio_button(&quot;post&quot;, &quot;category&quot;, &quot;rails&quot;)
  radio_button(&quot;post&quot;, &quot;category&quot;, &quot;java&quot;)
  # =&gt; &lt;input type=&quot;radio&quot; id=&quot;post_category&quot; name=&quot;post[category]&quot; value=&quot;rails&quot; checked=&quot;checked&quot; /&gt;
  #    &lt;input type=&quot;radio&quot; id=&quot;post_category&quot; name=&quot;post[category]&quot; value=&quot;java&quot; /&gt;

  radio_button(&quot;user&quot;, &quot;receive_newsletter&quot;, &quot;yes&quot;)
  radio_button(&quot;user&quot;, &quot;receive_newsletter&quot;, &quot;no&quot;)
  # =&gt; &lt;input type=&quot;radio&quot; id=&quot;user_receive_newsletter&quot; name=&quot;user[receive_newsletter]&quot; value=&quot;yes&quot; /&gt;
  #    &lt;input type=&quot;radio&quot; id=&quot;user_receive_newsletter&quot; name=&quot;user[receive_newsletter]&quot; value=&quot;no&quot; checked=&quot;checked&quot; /&gt;
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000929-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000929-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_view/helpers/form_helper.rb, line 421</span>
421:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">radio_button</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-identifier">tag_value</span>, <span class="ruby-identifier">options</span> = {})
422:         <span class="ruby-constant">InstanceTag</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-keyword kw">self</span>, <span class="ruby-keyword kw">nil</span>, <span class="ruby-identifier">options</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">:object</span>)).<span class="ruby-identifier">to_radio_button_tag</span>(<span class="ruby-identifier">tag_value</span>, <span class="ruby-identifier">options</span>)
423:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000927" class="method-detail">
        <a name="M000927"></a>

        <div class="method-heading">
          <a href="#M000927" class="method-signature">
          <span class="method-name">text_area</span><span class="method-args">(object_name, method, options = {})</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Returns a textarea opening and closing tag set tailored for accessing a
specified attribute (identified by <tt>method</tt>) on an object assigned
to the template (identified by <tt>object</tt>). Additional options on the
input tag can be passed as a hash with <tt>options</tt>.
</p>
<h4>Examples</h4>
<pre>
  text_area(:post, :body, :cols =&gt; 20, :rows =&gt; 40)
  # =&gt; &lt;textarea cols=&quot;20&quot; rows=&quot;40&quot; id=&quot;post_body&quot; name=&quot;post[body]&quot;&gt;
  #      #{@post.body}
  #    &lt;/textarea&gt;

  text_area(:comment, :text, :size =&gt; &quot;20x30&quot;)
  # =&gt; &lt;textarea cols=&quot;20&quot; rows=&quot;30&quot; id=&quot;comment_text&quot; name=&quot;comment[text]&quot;&gt;
  #      #{@comment.text}
  #    &lt;/textarea&gt;

  text_area(:application, :notes, :cols =&gt; 40, :rows =&gt; 15, :class =&gt; 'app_input')
  # =&gt; &lt;textarea cols=&quot;40&quot; rows=&quot;15&quot; id=&quot;application_notes&quot; name=&quot;application[notes]&quot; class=&quot;app_input&quot;&gt;
  #      #{@application.notes}
  #    &lt;/textarea&gt;

  text_area(:entry, :body, :size =&gt; &quot;20x20&quot;, :disabled =&gt; 'disabled')
  # =&gt; &lt;textarea cols=&quot;20&quot; rows=&quot;20&quot; id=&quot;entry_body&quot; name=&quot;entry[body]&quot; disabled=&quot;disabled&quot;&gt;
  #      #{@entry.body}
  #    &lt;/textarea&gt;
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000927-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000927-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_view/helpers/form_helper.rb, line 375</span>
375:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">text_area</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-identifier">options</span> = {})
376:         <span class="ruby-constant">InstanceTag</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-keyword kw">self</span>, <span class="ruby-keyword kw">nil</span>, <span class="ruby-identifier">options</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">:object</span>)).<span class="ruby-identifier">to_text_area_tag</span>(<span class="ruby-identifier">options</span>)
377:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000923" class="method-detail">
        <a name="M000923"></a>

        <div class="method-heading">
          <a href="#M000923" class="method-signature">
          <span class="method-name">text_field</span><span class="method-args">(object_name, method, options = {})</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Returns an input tag of the &quot;text&quot; type tailored for accessing a
specified attribute (identified by <tt>method</tt>) on an object assigned
to the template (identified by <tt>object</tt>). Additional options on the
input tag can be passed as a hash with <tt>options</tt>. These options will
be tagged onto the HTML as an HTML element attribute as in the example
shown.
</p>
<h4>Examples</h4>
<pre>
  text_field(:post, :title, :size =&gt; 20)
  # =&gt; &lt;input type=&quot;text&quot; id=&quot;post_title&quot; name=&quot;post[title]&quot; size=&quot;20&quot; value=&quot;#{@post.title}&quot; /&gt;

  text_field(:post, :title, :class =&gt; &quot;create_input&quot;)
  # =&gt; &lt;input type=&quot;text&quot; id=&quot;post_title&quot; name=&quot;post[title]&quot; value=&quot;#{@post.title}&quot; class=&quot;create_input&quot; /&gt;

  text_field(:session, :user, :onchange =&gt; &quot;if $('session[user]').value == 'admin' { alert('Your login can not be admin!'); }&quot;)
  # =&gt; &lt;input type=&quot;text&quot; id=&quot;session_user&quot; name=&quot;session[user]&quot; value=&quot;#{@session.user}&quot; onchange = &quot;if $('session[user]').value == 'admin' { alert('Your login can not be admin!'); }&quot;/&gt;

  text_field(:snippet, :code, :size =&gt; 20, :class =&gt; 'code_input')
  # =&gt; &lt;input type=&quot;text&quot; id=&quot;snippet_code&quot; name=&quot;snippet[code]&quot; size=&quot;20&quot; value=&quot;#{@snippet.code}&quot; class=&quot;code_input&quot; /&gt;
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000923-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000923-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_view/helpers/form_helper.rb, line 288</span>
288:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">text_field</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-identifier">options</span> = {})
289:         <span class="ruby-constant">InstanceTag</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">object_name</span>, <span class="ruby-identifier">method</span>, <span class="ruby-keyword kw">self</span>, <span class="ruby-keyword kw">nil</span>, <span class="ruby-identifier">options</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">:object</span>)).<span class="ruby-identifier">to_input_field_tag</span>(<span class="ruby-value str">&quot;text&quot;</span>, <span class="ruby-identifier">options</span>)
290:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>


    </div>


  </div>


<div id="validator-badges">
  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>

</body>
</html>